feat(http/unstable): add radix tree router; keep linear scan as routeLinear by esroyo · Pull Request #7075 · denoland/std

esroyo · 2026-03-31T20:08:52Z

Add routeRadix(), a radix tree router that provides O(segments) dispatch for static, parametric, and wildcard routes. Routes with complex URLPattern syntax (regex constraints, optional groups, inline wildcards, modifier suffixes) fall back to linear matching while preserving insertion order.

routeRadix: radix tree with fallback to linear for complex patterns
routeLinear: the original linear scan, extracted as its own export
route: re-exported alias for routeLinear

The radix router matches routeLinear semantics exactly; insertion order is always respected, even when static and parametric routes overlap at the same tree depth.

Benchmarks show 1.5–9x improvement on static/parametric/wildcard routes, with negligible overhead on complex fallback patterns.

---
config:
    themeVariables:
        xyChart:
            plotColorPalette: "#e05c5c, #4a90d9"
---
xychart-beta
    title "route: 🔴 linear vs 🔵 radix - Avg latency (µs)"
    x-axis [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
    y-axis "Avg latency (µs)" 0 --> 7

    line [0.91, 2.04, 6.1, 1.63, 5.54, 1.49, 2.84, 1.08, 3.15, 0.9, 1.45, 1.98]
    line [1.08, 1.38, 1.39, 0.62, 0.61, 1.55, 1.66, 0.91, 1.73, 1.46, 1.62, 2.1]

#	Group	🔴 linear (µs)	🔵 radix (µs)
1	static route — first in small table	0.91	1.08
2	static route — last in small table	2.04	1.38
3	static route — last in large table	6.1	1.39
4	static route — miss (small table)	1.63	0.62
5	static route — miss (large table)	5.54	0.61
6	parametric route — single param	1.49	1.55
7	parametric route — two params (nested)	2.84	1.66
8	parametric route — method mismatch	1.08	0.91
9	wildcard route	3.15	1.73
10	complex — regex constraint	0.9	1.46
11	complex — optional group	1.45	1.62
12	complex — inline wildcard with suffix	1.98	2.1

    CPU | AMD Ryzen 7 PRO 6850U with Radeon Graphics
Runtime | Deno 2.7.9 (x86_64-unknown-linux-gnu)

file:///../denoland/std/http/unstable_route_bench.ts

| benchmark   | time/iter (avg) |        iter/s |      (min … max)      |      p75 |      p99 |     p995 |
| ----------- | --------------- | ------------- | --------------------- | -------- | -------- | -------- |

group static route — first in small table
| linear      |        921.1 ns |     1,086,000 | (869.7 ns …   1.4 µs) | 921.5 ns |   1.4 µs |   1.4 µs |
| radix       |          1.1 µs |       885,100 | (  1.1 µs …   1.3 µs) |   1.1 µs |   1.3 µs |   1.3 µs |

summary
  linear
     1.23x faster than radix

group static route — last in small table
| linear      |          2.0 µs |       494,200 | (  2.0 µs …   2.6 µs) |   2.0 µs |   2.6 µs |   2.6 µs |
| radix       |          1.3 µs |       751,200 | (  1.3 µs …   1.7 µs) |   1.3 µs |   1.7 µs |   1.7 µs |

summary
  linear
     1.52x slower than radix

group static route — last in large table
| linear      |          5.9 µs |       170,100 | (  5.8 µs …   6.1 µs) |   5.9 µs |   6.1 µs |   6.1 µs |
| radix       |          1.3 µs |       750,600 | (  1.3 µs …   1.6 µs) |   1.3 µs |   1.6 µs |   1.6 µs |

summary
  linear
     4.41x slower than radix

group static route — miss (small table)
| linear      |          1.7 µs |       596,400 | (  1.6 µs …   2.1 µs) |   1.7 µs |   2.1 µs |   2.1 µs |
| radix       |        622.6 ns |     1,606,000 | (600.0 ns … 702.4 ns) | 621.7 ns | 702.4 ns | 702.4 ns |

summary
  linear
     2.69x slower than radix

group static route — miss (large table)
| linear      |          5.6 µs |       179,100 | (  5.4 µs …   5.9 µs) |   5.6 µs |   5.9 µs |   5.9 µs |
| radix       |        606.1 ns |     1,650,000 | (594.0 ns … 641.1 ns) | 610.5 ns | 641.1 ns | 641.1 ns |

summary
  linear
     9.21x slower than radix

group parametric route — single param
| linear      |          1.5 µs |       645,600 | (  1.5 µs …   1.7 µs) |   1.6 µs |   1.7 µs |   1.7 µs |
| radix       |          1.5 µs |       649,500 | (  1.5 µs …   1.9 µs) |   1.5 µs |   1.9 µs |   1.9 µs |

summary
  linear
     1.01x slower than radix

group parametric route — two params (nested)
| linear      |          2.8 µs |       360,900 | (  2.7 µs …   2.9 µs) |   2.8 µs |   2.9 µs |   2.9 µs |
| radix       |          1.6 µs |       614,300 | (  1.6 µs …   1.7 µs) |   1.7 µs |   1.7 µs |   1.7 µs |

summary
  linear
     1.70x slower than radix

group parametric route — method mismatch
| linear      |          1.1 µs |       924,900 | (  1.0 µs …   1.4 µs) |   1.1 µs |   1.4 µs |   1.4 µs |
| radix       |        929.0 ns |     1,076,000 | (900.7 ns … 980.0 ns) | 933.5 ns | 980.0 ns | 980.0 ns |

summary
  linear
     1.16x slower than radix

group wildcard route
| linear      |          3.2 µs |       314,400 | (  3.1 µs …   3.6 µs) |   3.2 µs |   3.6 µs |   3.6 µs |
| radix       |          1.7 µs |       600,900 | (  1.6 µs …   2.0 µs) |   1.7 µs |   2.0 µs |   2.0 µs |

summary
  linear
     1.91x slower than radix

group complex — regex constraint
| linear      |        947.0 ns |     1,056,000 | (908.1 ns …   1.3 µs) | 947.5 ns |   1.3 µs |   1.3 µs |
| radix       |          1.5 µs |       673,300 | (  1.4 µs …   1.7 µs) |   1.5 µs |   1.7 µs |   1.7 µs |

summary
  linear
     1.57x faster than radix

group complex — optional group
| linear      |          1.5 µs |       680,000 | (  1.4 µs …   1.7 µs) |   1.5 µs |   1.7 µs |   1.7 µs |
| radix       |          1.6 µs |       625,800 | (  1.6 µs …   1.8 µs) |   1.6 µs |   1.8 µs |   1.8 µs |

summary
  linear
     1.09x faster than radix

group complex — inline wildcard with suffix
| linear      |          1.9 µs |       529,200 | (  1.8 µs …   2.1 µs) |   1.9 µs |   2.1 µs |   2.1 µs |
| radix       |          2.0 µs |       490,400 | (  2.0 µs …   2.2 µs) |   2.0 µs |   2.2 µs |   2.2 µs |

summary
  linear
     1.08x faster than radix

CLAassistant · 2026-03-31T20:09:02Z

All committers have signed the CLA.

codecov · 2026-03-31T20:13:02Z

Codecov Report

❌ Patch coverage is 93.67089% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.60%. Comparing base (cd03740) to head (632ecdc).

Files with missing lines	Patch %	Lines
http/unstable_route.ts	93.67%	7 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7075      +/-   ##
==========================================
- Coverage   94.61%   94.60%   -0.01%     
==========================================
  Files         634      634              
  Lines       51799    51942     +143     
  Branches     9329     9376      +47     
==========================================
+ Hits        49009    49141     +132     
- Misses       2216     2223       +7     
- Partials      574      578       +4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…Linear Add routeRadix(), a radix tree router that provides O(segments) dispatch for static, parametric, and wildcard routes. Routes with complex URLPattern syntax (regex constraints, optional groups, inline wildcards, modifier suffixes) fall back to linear matching while preserving insertion order. - routeRadix: radix tree with fallback to linear for complex patterns - routeLinear: the original linear scan, extracted as its own export - route: re-exported alias for routeRadix (backward compatible) The radix router matches routeLinear semantics exactly — insertion order is always respected, even when static and parametric routes overlap at the same tree depth. Benchmarks show 1.5–9x improvement on static/parametric/wildcard routes, with negligible overhead on complex fallback patterns.

Replace the per-request `radixCandidates` array + `Array#sort` + merge with a single-slot match using `minIndex` pruning and inline pathname iteration. No candidate array, segments array, or sort closure on the hot path. Each `RouteNode` now tracks `minIndex` (lowest insertion index in the subtree) and `hasStaticChildren` (skip the substring slice when there are no static children). Fallback routes registered before the lowest radix index are scanned first so their hits prune the tree walk.

…allback URLPattern requires reserved characters (`+`, `?`, `*`) to be backslash-escaped to match literally. The escape is preserved in `pattern.pathname` (e.g. `/c\+\+`), so the radix tree was inserting such patterns as static keys that could never match the unescaped request path (`/c++`), making those routes unreachable. Treat any segment containing a backslash as complex so URLPattern remains the authoritative matcher via the linear fallback. Adds a regression test covering both single (`\+`) and consecutive (`\+\+`) escape forms.

The radix router is brand new; keep `route` bound to the better-tested `routeLinear` while it matures. Users who want the radix optimizations opt in via the `routeRadix` named export.

esroyo · 2026-04-30T22:34:04Z

@bartlomieju Thank you for the insightful comments! I mostly agree with your feedback (except the Array#sort comment perhaps) and have addressed all the points you raised. Thanks so much for your time ❤️

esroyo · 2026-04-30T22:41:56Z

[updated]

---
config:
    themeVariables:
        xyChart:
            plotColorPalette: "#e05c5c, #4a90d9"
---
xychart-beta
    title "AMD Ryzen 7 PRO 6850U — route benchmark"
    x-axis [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
    y-axis "Avg latency (µs)" 0 --> 6

    line [0.92, 1.96, 5.86, 1.63, 5.6, 1.53, 2.72, 1.06, 3.17, 0.93, 1.46, 1.89]
    line [1, 1.12, 1.07, 0.43, 0.43, 1.18, 1.31, 0.54, 1.39, 1.05, 1.44, 1.88]

🔴 linear 🔵 radix

#	Group	🔴 linear (µs)	🔵 radix (µs)
1	static route — first in small table	0.92	1
2	static route — last in small table	1.96	1.12
3	static route — last in large table	5.86	1.07
4	static route — miss (small table)	1.63	0.43
5	static route — miss (large table)	5.6	0.43
6	parametric route — single param	1.53	1.18
7	parametric route — two params (nested)	2.72	1.31
8	parametric route — method mismatch	1.06	0.54
9	wildcard route	3.17	1.39
10	complex — regex constraint	0.93	1.05
11	complex — optional group	1.46	1.44
12	complex — inline wildcard with suffix	1.89	1.88

github-actions Bot added the http label Mar 31, 2026

esroyo force-pushed the unstable-route-radix branch from 786873d to d522ffa Compare March 31, 2026 20:19

bartlomieju reviewed Apr 9, 2026

View reviewed changes

Comment thread http/unstable_route.ts Outdated

Comment thread http/unstable_route.ts Outdated

Comment thread http/unstable_route.ts

Comment thread http/unstable_route.ts Outdated

Comment thread http/unstable_route.ts Outdated

Comment thread http/unstable_route.ts

esroyo added 4 commits May 1, 2026 00:02

refactor(http/unstable): default route export to routeLinear

632ecdc

The radix router is brand new; keep `route` bound to the better-tested `routeLinear` while it matures. Users who want the radix optimizations opt in via the `routeRadix` named export.

esroyo force-pushed the unstable-route-radix branch from 8b90273 to 632ecdc Compare April 30, 2026 22:02

esroyo requested a review from bartlomieju April 30, 2026 22:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(http/unstable): add radix tree router; keep linear scan as routeLinear#7075

feat(http/unstable): add radix tree router; keep linear scan as routeLinear#7075
esroyo wants to merge 4 commits intodenoland:mainfrom
esroyo:unstable-route-radix

esroyo commented Mar 31, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Mar 31, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

esroyo commented Apr 30, 2026 •

edited

Loading

Uh oh!

esroyo commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

esroyo commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

esroyo commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

esroyo commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

esroyo commented Mar 31, 2026 •

edited

Loading

CLAassistant commented Mar 31, 2026 •

edited

Loading

codecov Bot commented Mar 31, 2026 •

edited

Loading

esroyo commented Apr 30, 2026 •

edited

Loading